---
sidebar_label: Mobile guide (Beta)
sidebar_position: 4
description: "Learn how to use the Hanko backend with your mobile apps."
---

# Mobile guide

Currently, we do not provide SDKs that make the integration for mobile apps as easy as the [Hanko element web component](/guides/frontend).
In this guide you will learn what you need to do in order to use the [Hanko backend](https://github.com/teamhanko/hanko/backend) with your native app.

## Overview

This section shows a high level overview of the steps you need to perform in your app in order to have the same flow as in our web component.
In the [Steps](#steps) section we provide more details about each step.

1. [Check if the user exists](#check-if-the-user-exists)
2. [If the user does not exist, create the user](#create-user)
3. [Send a passcode to the user](#send-a-passcode)
4. [(optional) Offer to create a passkey](#create-a-passkey-optional)
5. [(optional) Login with a passkey](#login-with-a-passkey-optional)

:::info

This guide focuses on the passwordless flow, so passwords will be ignored.

:::

:::info

Passkeys are only supported on iOS 16+ and Android 9+.

:::

## Steps

### Check if the user exists

After an email input was shown and the user provided their email, you should check if the user already exists.
You can do that by using the [Get user details by email](/api/public#tag/User-Management/operation/getUserId) endpoint.

You will either get an HTTP status code of `200` or `404`. If you get `200`, remember the `id` returned in the response object and go to step [Send a passcode](#send-a-passcode).
If you get `404`, go to the [next step](#create-user).

### Create user

When the user does not already exist, you will need to create the user before you can verify the email. The user can be created using the [Create a user](/api/public#tag/User-Management/operation/createUser) endpoint.

You will either get an HTTP status code of `200` or `409`. If you get `409`, then the user already exists, and you can obtain the users `id` from the success response of the endpoint mentioned in the [previous step](#check-if-user-exist).
If you get `200`, remember the `id` returned in the response object.

### Send a passcode

To verify an email address or to log in the user, you need to send a passcode to the provided email address and verify that the user has access to it. To send a passcode just use the [Initialize passcode login](/api/public#tag/Passcode/operation/passcodeInit) endpoint.
You need to provide the user's `id` you obtained in one of the previous steps. If sending the passcode was successful, you will get an `id` for the passcode in the response object. Remember this `id`, because you will need it to finalize the passcode flow.

When the user entered the passcode, send it together with the passcode `id` from the [Init endpoint](/api/public#tag/Passcode/operation/passcodeInit) to the [Finalize passcode login](/api/public#tag/Passcode/operation/passcodeFinal) endpoint.
When the passcode is correct you will get a JWT either as a cookie or in the `X-Auth-Token` header (depends on the configuration of the Hanko backend) .

The user is now logged in. To verify (in your backend) that the JWT is valid, see our [Backend guide](/guides/backend).

Optionally you can offer the user to register a passkey now, enabling a faster login flow the next time. See the next step on how to do it.

### Create a passkey (optional)

To create a passkey you will need to use the native APIs that [Google](https://developers.google.com/identity/fido/android/native-apps)
and [Apple](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
provide for their platforms. Find out how to use them [here](https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys)
(Apple) and [here](https://codelabs.developers.google.com/codelabs/fido2-for-android#0) (Android).

For both you will need `PublicKeyCredentialAttestationOptions` which you can get from the [Initialize WebAuthn registration](/api/public#tag/WebAuthn/operation/webauthnRegInit) endpoint.

After the native system APIs were called with the options you will receive a `PublicKeyCredentialAttestationResponse`. Send the response to the [Finalize WebAuthn registration](/api/public#tag/WebAuthn/operation/webauthnRegFinal) endpoint.
If successful, the user can use the created passkey to login faster the next time.

:::info

The two endpoints ([Initialize WebAuthn registration](/api/public#tag/WebAuthn/operation/webauthnRegInit) and [Finalize WebAuthn registration](/api/public#tag/WebAuthn/operation/webauthnRegFinal)) mentioned above can only be called with a valid JWT.

:::

:::info

In order for **Android** to work with the [Hanko backend](https://github.com/teamhanko/hanko) you will need to add an "APK Key Hash" to either `webauthn.relying_party.origins` or in the advanced page in the settings at [Hanko Cloud](https://cloud.hanko.io).
Use this command to create the "APK Key Hash":
```shell
echo 'android:apk-key-hash:'"$(keytool -exportcert -alias key-name -keystore path-to-keystore | openssl sha256 -binary | openssl base64 | tr -- '+/' '-_' | tr -d '=')"
```

Change `-alias` and `-keystore` flag values to your personal values.

:::

### Login with a passkey (optional)

In order to use a passkey for login, add a button ("Sign in with a passkey") under your email input. After interaction with the button, call the native APIs that [Google](https://developers.google.com/identity/fido/android/native-apps)
and [Apple](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider).
Find out how to use them [here](https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys)
(Apple) and [here](https://codelabs.developers.google.com/codelabs/fido2-for-android#0) (Android).

For both you will need `PublicKeyCredentialAssertionOptions` which you can get from the [Initialize WebAuthn login](/api/public#tag/WebAuthn/operation/webauthnLoginInit) endpoint.

After the native system APIs were called with the options you will receive a `PublicKeyCredentialAssertionResponse`. Send the response to the [Finalize WebAuthn login](/api/public#tag/WebAuthn/operation/webauthnLoginFinal) endpoint.
If successful you will get back a JWT either as a cookie or in the `X-Auth-Token` header (depends on the configuration of the Hanko backend).

The user is now logged in. To verify (in your backend) that the JWT is valid, see our [Backend guide](/guides/backend).
